PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/pascal/tp_asm.exe/TP&ASM.DOC

Text File | 1989-07-22 | 21.4 KB | 555 lines

  TP&Asm           Integrated Compile-Time Assembler          Version 2.2

                Copyright (c) 1989  Richard W. Prescott
                          All Rights Reserved

═══════ Built-In Assembly Language Support for Turbo Pascal Compilers ═══════

 All brand and product names mentioned herein are trademarks or registered
                trademarks of their respective holders.

  ┌─────────────────────────────────────────────────────────────────────┐
  │  This file contains information of a general nature, including      │
  │  getting started quickly, and purchasing TP&Asm.  For detailed      │
  │  reference information to enable you to make most effective use of  │
  │  the TP&Asm assembly environment, please see the archive TP-AsR     │
  └─────────────────────────────────────────────────────────────────────┘


The following topics are described below:

1. Overview
2. Features
3. System Requirements
4. Getting Started
5. Comparison of Methods
6. Quality Control
7. DISCLAIMER
8. Purchase Information




Note:

This archive contains a complete, unlimited version of TP&Asm which is
being distributed as "shareware".  No features have been disabled, and
nothing has been omitted from the documentation contained in this file
or in the separate reference archive.  It differs from the version you
get when you register only in that it contains a reminder to register,
which pops up the first time you compile to disk after running TP&Asm.
(Registered users also receive the source code for EXAMINE.EXE and the
WCHMGR5x.TPU files).

Except for this distinction, all references to TP&Asm or TPA.EXE apply
to the program file TPA(E).EXE contained in this archive. You may find
it convenient to rename  TPA(E).EXE to TPA.EXE, however please use the
original name whenever you redistribute this archive.

If you like this program, and use it, then please order a registered
copy.  As an incentive to register early, I am offering a $10 discount
to all orders received by 8/31/89:
 ┌─────────────────────────────────────────────────────────────────┐
 │ TP&Asm Version 2.2: $39 + $3 P&H  Reduced Price (until 8/31/89) │
 └─────────────────────────────────────────────────────────────────┘
Please see section 8 for further registration information.




1. Overview

TP&Asm is an integrated assembler for Turbo Pascal versions 5.5, 5.0,
and 4.0 which operates during the compile step to provide support for
the four TP&Asm keywords "Assemble" (or "Assembly"), "Internal",
"CsData", and "Asm":

      Assemble                       Internal <DataName>
        :                              :
        (Assembly                      (Assembly
         Instructions)                  Instructions)
        :                              :
      End;                           End;


      CsData
        :
        (Db, Dw, or Dd
         Statements)
        :
      End;


      Asm <Assembly Statement>;


Briefly:

  "Assemble" defines a block of standard 8086 assembly language
    statements which can be placed wherever an Inline statement
    would be valid (including 'Inline Directives').

  "Internal" provides support for assembly language code originally
    designed for an external assembler.

  "CsData" defines a block of initialized or uninitialized data
    which is allocated in the current Code segment and is
    accessable throughout the current Unit (used primarily with
    customized interrupt procedures and resident applications).

  "Asm" provides a concise way of specifying single-line assembly
    sections.


As of Version 2.2, the following compilers are supported:

      TURBO.EXE    Versions 5.5, 5.0, and 4.0
      TPC.EXE      Versions 5.5, 5.0, and 4.0


Example:

The following simple functions compile successfully when a
supported compiler is run under TP&Asm:

  FUNCTION ReadScan:Byte; {Read keyboard scan code without echo to screen}
   Assembly             {- Inline Directive -}
    Mov Ah,0
    Int 16h
    Mov Al,Ah           ;Put Assembly/Inline Directive result in Al
   END; {Assembly}

 - or -

  FUNCTION ReadScan:Byte; {Read keyboard scan code without echo to screen}
  BEGIN                 {- Standard Callable Function -}
   Assembly
    Mov Ah,0
    Int 16h
    Mov ReadScan,Ah     ;Put in standard function results by name
   END; {Assembly}
  END; {FUNCTION ReadScan}


Please see the various PAS files in this archive for further
examples.



2. Features of TP&Asm

 o Runs Turbo/TPC as a subprocess.  Simple to use, yet powerful
   enough to run ANY command line under TP&Asm.  For example,
   "tpa C:\Command" can be used to make TP&Asm "Memory resident".
   See the reference archive TP-AsR.

 o Compact: Program size 44K, TOTAL Memory usage less than 54K
   (Frees its own "environment" block for reuse by the subprocess)

   - yet -

 o Imposes NO limits on Source Code size, Object Code size, or Data
   Seg symbols.  (Your program must still satisfy any Compiler
   limits, however)

 o Fast Assembly from Memory - TP&Asm imposes NO additional disk
   access time, even for Include files.

 o Fully compatible with the Turbo 5.0/5.5 integrated debugger.
   The units WCHMGR5x (included) allow you to Watch, Evaluate, and
   Modify the state of all CPU registers and flags.

 o Fully integrated with the Turbo built-in Linker.  Permits direct
   Call, Jmp, and Offset references to Pascal Proc/Functions.
   (These references are recognized by the Turbo Smart Linker).

   - yet -

   Units compiled with TP&Asm may be Used in any Turbo Pascal
   program compiled with or without TP&Asm.

 o Fully supports references to Turbo 5.5 objects and methods.
   Supports Static and Virtual method calls BY NAME rather than
   user-calculated VMT offsets, as well as assembly references to
   "Self" and "VMT".  You can redesign any object structure without
   rewriting any (TP&Asm) assembly code.  (Not so with External!)

 o Freely mix Pascal and assembly sections.  Pascal Labels placed
   in assembly sections can be the target of any GOTO statement.
   Assembly statements can branch to (Jmp, Loop, jNZ, etc) or Call
   any Pascal or assembly label.

 o Performs automatic Jump-Sizing for all backward AND FORWARD
   Jumps and Loops.  Always builds smallest possible instruction
   (does not pad code with NOPs).

 o Supports all 8086 Assembly mnemonics and all assembler directives
   that make sense within a Turbo Pascal program.

 o Supports numerous extensions for compatibility with Eric
   Isaacson's A86 Assembler (Multiple operands to Push, IF's, Local
   Labels, etc).

 o Recognizes all common decimal and hexidecimal numeric formats,
   including leading '$' for compatibility with Dave Baldwin's
   INLINE.COM.

 o Automatically supplies correct segment override and base register
   needed to reference most Pascal and Assembly variables.  (This
   feature may be disabled for "WYSIWYG" assembly).

 o Allows setting function results by name, e.g.:
   "Mov FunctionName,TRUE" (Automatically recognizes Built-In
   compiler symbols such as TRUE).

 o Provides extensive syntax error checking, completely integrated
   with the compiler's syntax checking.  The cursor is placed at the
   point in your assembly language code where the error occurred.

 o Supports Warning level errors, with option to Ignore or Halt on
   warnings.

 o Does not disable "Inline" or "External" - these keywords are
   still available, but are no longer necessary.  Any or all of
   the keywords Assemble, Internal, External, and Inline may be
   used in each program or unit.



3. System Requirements

TP&Asm Version 2.2 requires: the IBM PC version of Turbo Pascal 5.5,
5.0, or 4.0 running on an IBM PC or Compatible, with Version 2.0 or
above of MS-DOS or PC-DOS.  Minimum memory requirements are 54K more
than the memory required by the compiler.



4. Getting Started

Simply type 'tpa' { or 'tpa(e)' } in place of 'turbo' at the system
prompt.  TP&Asm will automatically find and run turbo.exe, using
the same search sequence as DOS.  Or run the command line compiler
by typing 'tpa tpc progname' or 'tpa c progname'.  (See the archive
TP-AsR for other command line options when starting TP&Asm).

Now read in some of the test files.  Browse through them to see
what they do, then compile and run them.  Modify them and run again.
Version 5.0 and 5.5 users, use F7 "Trace into" to step through the
file DEMOTPA.PAS (which automatically sets up a series of assembly
level watch expressions) and observe the CPU registers and flags
as you trace through the assembly code.  Observe how easy it is to
experiment with assembly language in your programs.  Observe the
response to syntax errors.  TP&Asm does not intrude into your
programming environment - you are running Turbo Pascal, and the
assembler is integrated so smoothly into the system that you may
forget you are using it.  It is active, however, every time the
compiler calls upon it to translate an Assemble or Internal
statement.



5. A Comparison of (Assembly Language) Methods

This section discusses advantages and disadvantages of the four
basic methods of using machine code/assembly language within a Turbo
Pascal program:  Inline and External (as provided by Turbo Pascal),
and Internal and Assemble (provided by TP&Asm).  (Skip this section
if you're already convinced).

INLINE:

The disadvantage of the Inline statement is obvious - no support for
mnemonics.  Every instruction must be assembled by hand, jumps and
loops are essentially impossible, etc.  Direct calls to Pascal
Procedures and Functions are not permitted.

An advantage, however, is that code may be placed anywhere in the
code stream, not just into separate callable Proc/Functions, and
Turbo identifiers may be referenced by name.  In addition, Inline
statements may be used to define machine code MACROs.

EXTERNAL:

The advantage of External is, just as obviously, full support of
assembly mnemonics (or whatever subset is supported by your external
assembler).  May also permit access to the symbol "SEG DATA" for
restoring the program Data Segment (useful in interrupt routines).

Disadvantages of External are:

  Code must always go into separate callable Global Proc/Functions.

  Limited support for Global Pascal identifier references.
   UnitName and record component qualifiers are not permitted.
   Referenced identifiers must be declared in EXTRN statements.

  Limited "dead code removal" - Turbo Pascal links in External .OBJ
   modules in an "all or nothing" fashion.

  All references to Proc/Function parameters and Function results
   returned on the stack must be coded explicitly (not referenced
   by name) and may need to be changed for future versions of the
   compiler.  Note however that Borland's TASM provides the
   ".MODEL TPASCAL" directive which permits the same simplified
   parameter references as the TP&Asm Assemble statement.


INTERNAL:

Internal is essentially a direct replacement for External,
supporting 8086 Assembly mnemonics and access to the symbol
"SEG DATA".

Improvements:

  Full support for Global Pascal variable references with no need
   for EXTRN.  Supports UnitName, record component, and object
   component qualifiers.

  Fully supports direct and virtual method calls by name, rather
   than by user-calculated VMT offsets, permitting insertion and
   removal of virtual methods without rewriting any assembly code.

  Full "dead code removal" on a Proc by Proc basis within each
   INTERNAL statement.  Permits development of efficient libraries
   of assembly routines compiled into standard Turbo Pascal TPUs.

Unchanged:

  Code still must go into separate callable Global procs.

  Parameter and function results must still be explicitly coded.


ASSEMBLE:

Advantages:

  As with External, supports 8086 Assembly mnemonics and access to
   the symbol "SEG DATA" (8087 mnemonics are not yet supported).

  As with Inline, code may be placed anywhere in the code stream,
   INCLUDING in the definition of (assembly) Inline Directive/MACROs

  As with Internal, provides full support for global Pascal variable
   references without EXTRN, including UnitName and record component
   qualifiers.  Permits direct Call (or Jmp) to any Pascal or Internal
   Proc/Function, and direct or virtual calls to version 5.5 methods.

  In fact, all Pascal variables/parameters which are global or local
   to the current Proc/Function may be referenced by the standard
   Pascal name (without '[BP]', 'CS', etc.).  Function results may
   likewise be put in by name.  There is no need to be concerned
   with the details of Stack usage and parameter passing for any
   particular compiler version.

  Provides capability of allocating and referencing NAMED
   initialized (or uninitialized) data in the current code seg.


To summarize,

 In terms of coding convenience:
    - External is a major improvement over Inline
    - Internal is a moderate improvement over External
    - Assemble is a major improvement over Internal and External

 In terms of flexibility of use, however, Assemble and Inline have
 advantages over External and Internal.


It should be clear at this point that the Assemble statement provides
the most versatile and convenient means of including assembly
language in your programs.  Now consider the fact that with Assemble
(and Internal) you don't need to leave the compiler at any point
during your program development, and you can see that TP&Asm offers
you an immense improvement in program development speed.  The time
consuming assembly development loop of:
Exit Turbo/ Assemble/ Reenter Turbo/ Compile &/or Link/ Test/ Repeat
is replaced by the simple and familiar  Edit/Run/Repeat  loop.
With TP&Asm you can be wrapped up & on your way home while others
are still watching their assemblers clean up temporary disk files.

Or if you primarily use TPC, consider how many ASM and OBJ files you
have littering your directories.  With TP&Asm you can put all related
assembly routines into a single PAS file and compile to a single TPU
which provides Proc by Proc Smart-Linking and can be automatically
rebuilt by TPC whenever you modify your assembly source code.

Even if your primary goal is to write stand-alone assembly programs,
consider the advantage of using Turbo/TP&Asm as a program
development environment.  You can develop, test and debug your
assembly routines using all the power and flexibility of Pascal in
the testing process - then port your code unchanged** to A86 or
your favorite stand-alone assembler.  See, for example, HEXBYTE.PAS.

** regarding compatability:  essentially, it is a simple matter to
   design your code so that it requires NO changes in porting from
   TP&Asm to A86, MASM, TASM, or any assembler that is reasonably
   compatible with one of these.  You must of course avoid using
   any TP&Asm enhancements that are not supported by your assembler.



The paragraphs above address the issue of why you should use TP&Asm
when you use assembly language ... but why use assembly language at
all?

The principal reasons for using assembly language in a Pascal
program are:

  1) To do something that cannot be done in Pascal.  This might
     involve a resident application, or some sort of direct
     interaction with the system hardware.  See for example the
     archives TP-TSR and TP-TRC described in the README file.

  2) To do something much faster than it can be done in Pascal.
     The file FIND.PAS provides a demonstration.

  3) To minimize code size or stack requirements, especially for
     "memory resident" programs.  (When code size is critical,
     however, the entire application would probably be written
     in assembly).


With TP&Asm you can put assembly code exactly (and only) where you
want it, and let the compiler handle everything else.



6. Quality Control

This program has been tested by assembling over 6000 variations of
assembly language statements and running the Turbo/TP&Asm output
Exe file through EXAMINE.EXE to produce a "side by side" display
of each assembly source statement together with its corresponding
DEBUG.COM disassembly.  All modifications are retested against the
same test files.  EXAMINE.EXE is provided free of charge on the
TP&Asm distribution disk so that users may easily verify proper
assembly within their own programs.  It can also be found in the
archive TP-XMN as described in the README file.  (EXAMINE requires
a compiled EXE and MAP file and a copy of DEBUG.COM).


TP&Asm Version 2.2 is compiled and assembled using TP&Asm Version
2.2 running Turbo Pascal Version 5.5.



7. DISCLAIMER OF WARRANTY

This software and accompanying documentation are sold "as is" and
without warranties as to performance or merchantability.

This program is sold without any express or implied warranties
whatsoever.  Because of the diversity of conditions and hardware
under which this program may be used, no warranty of fitness for a
particular purpose is offered.  The user is advised to test the
program thoroughly before relying on it.  THE USER MUST ASSUME THE
ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE AUTHOR WILL
BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF THE
PURCHASE PRICE.



8. Purchase Information.

After you have reviewed the TP&Asm package for a reasonable period
of time (say, 30 days), please register it if you plan to continue
using it.  Even if you choose not to register, I encourage you to
retain a copy of TP&Asm and distribute it to others via BBS or on
diskette.  Please include all files in both this archive and the
reference archive TP-AsR (if you have it).

If you find that this software does not perform as described, please
let me know.  I am proud of this program and I want it to work right
for you.  If you are dissatisfied, I will refund your purchase price.
I only ask that you clearly state the manner in which it failed to
perform as described when you return the distribution disk (and, of
course, that you discontinue using the program).  I will accept your
judgement without argument.  Consider the spirit in which this offer
is made, and please be fair.


The current prices are as follows:

TP&Asm Version 2.2  ... $39 + $3 P&H  Reduced Price (until 8/31/89)
                    ... $49 + $3 P&H  Regular Price (after 8/31/89)

Registered owners of any TP&Asm version can receive a full upgrade
to TP&Asm version 2.2 for $5 + $3 P&H.


Wisconsin residents, please add 5% sales tax.  Overseas orders,
please send a bank check in $US.

All prices listed are for standard 5 1/4 inch floppy disks.  Add
$2 for distribution on 3 1/2 inch disks.


Please send a check or money order payable to:

                      Richard W. Prescott
                      21 Mondale Court
                      Madison, WI  53705

Please include the following information:

  1. Full Version number of the Turbo Pascal compiler you now use.

  2. (Optional) Your registration number for that compiler.  This
     could be useful in tracking problem reports.

  3. If you obtained TP&Asm from a bulletin board:
     3a. Name, area code and phone number of that bulletin board
     3b. Full Version number of the TP&Asm version you have
     3c. Directory Date of the README file





The full shareware package, including this archive, the reference
archive, and the archive TP-XMN, is available for $5 + $3 P&H.
Use this option if it's cheaper than your connect charges, or if
you feel more comfortable getting the software directly from me.
If you subsequently decide to register you may deduct $5 from the
above listed prices.

         ----------------end-of-author's-documentation---------------

                        Software Library Information:

                   This disk copy provided as a service of

                        The Public (Software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  The P(s)L cannot de-
         bug programs over the telephone.

         Disks in the P(s)L are updated monthly, so if you did not get
         this disk  directly from the P(s)L,  you should be aware that
         the files in this set may no  longer be the current versions.

         For a copy of the latest monthly software library newsletter
         and a list of the 2,000+ disks in the library, call or write

                        The Public (Software) Library
                              P.O.Box 35705 - F
                           Houston, TX 77235-5705
                               [phone]